Add a report-only style-compatibility preflight and the applicable-slot matrix - #452

scripts/gen_capability_matrix.py (1)

66-74: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Derive the native slot-style count from the registry.

counts['slots_styleable_natively'] is dynamic, but Line 69 hard-codes nine and the root exception. If a slot changes its channel or native support, the generated summary can become stale while the table and total remain current. Add a registry-derived count for the styles={...} path, or remove the numeric split. The generated spec/api/capability-matrix.md summary inherits this literal.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/gen_capability_matrix.py` around lines 66 - 74, Update the summary
generation near counts['slots_styleable_natively'] to derive the styles={...}
slot count from the capability registry instead of hard-coding “nine” and the
root exception. Reuse the registry’s native-support/channel data so the
generated prose stays synchronized with the table and total when slots change.

python/xy/styling/preflight.py (3)

42-43: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Classify the writer family from an explicit format set.

Line 183 treats every non-raster format as vector, and _VECTOR_FORMATS is never read. A format added later to export._normalize_format would silently be reported against the vector subset. Select the family from both sets and refuse an unclassified format.

♻️ Proposed change

-def _styles_finding(slot: str, decls: dict[str, Any], fmt: str) -> SlotFinding:
-    meta = _SLOTS_BY_ID[slot]
-    family = "native_raster" if fmt in _RASTER_FORMATS else "native_vector"
+def _slot_family(fmt: str) -> str:
+    if fmt in _RASTER_FORMATS:
+        return "native_raster"
+    if fmt in _VECTOR_FORMATS:
+        return "native_vector"
+    raise ValueError(f"preflight has no writer family for format {fmt!r}")
+
+
+def _styles_finding(slot: str, decls: dict[str, Any], fmt: str) -> SlotFinding:
+    meta = _SLOTS_BY_ID[slot]
+    family = _slot_family(fmt)

_honored_props reads fmt in _RASTER_FORMATS for the same decision, so it can take the resolved family instead of re-deriving it.

Also applies to: 183-183

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/xy/styling/preflight.py` around lines 42 - 43, Update the
writer-family classification near _honored_props to resolve the format
explicitly against _RASTER_FORMATS and _VECTOR_FORMATS, rather than treating
every non-raster format as vector. Reject or otherwise fail clearly for formats
in neither set, then pass the resolved family through so _honored_props does not
re-derive it from fmt.

---

61-80: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

sources makes the frozen report mutable and unhashable.

StyleCompatibilityReport is frozen=True, but sources holds a plain dict, so a caller can mutate the report contents after it is returned. The generated __hash__ also fails on the dict field, so the report cannot go into a set or a dict key even though every other field is hashable. A Mapping field normalized at construction keeps the report read-only.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/xy/styling/preflight.py` around lines 61 - 80, Update
StyleCompatibilityReport.sources to use an immutable Mapping representation
rather than a plain dict, and normalize incoming mappings during construction so
callers cannot mutate the frozen report. Ensure the normalized sources value
remains hashable for generated __hash__ support while preserving existing source
lookups and defaults.

---

275-281: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Do not skip invalid style entries in preflight. Figure.class_names and Figure.chrome_styles are directly assignable, so callers can request a report before _dom_spec validates them. Report unknown slots and non-dict declarations explicitly, or validate them before routing.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/xy/styling/preflight.py` around lines 275 - 281, Update the preflight
finding collection around Figure.class_names and Figure.chrome_styles so invalid
entries are not silently skipped before _dom_spec validation. Report unknown
slots and non-dict chrome style declarations explicitly, or route them through
the existing validation logic before creating _class_finding or _styles_finding
results.

python/xy/_figure.py (1)

2220-2237: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

style_compatibility_report returns Any at both public entry points. The preflight module returns StyleCompatibilityReport, and preflight imports Figure only under TYPE_CHECKING, so both call sites can import the report type under TYPE_CHECKING without a runtime import cycle. Callers then get type checking on lossless, findings, losses, and explain().

• python/xy/_figure.py#L2220-L2237: add from .styling.preflight import StyleCompatibilityReport to the TYPE_CHECKING block and change the return annotation from Any to "StyleCompatibilityReport".
• python/xy/components.py#L4172-L4191: add the same TYPE_CHECKING import and change Chart.style_compatibility_report to return "StyleCompatibilityReport".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/xy/_figure.py` around lines 2220 - 2237, Replace the public Any return
annotations for style_compatibility_report with StyleCompatibilityReport and add
the report-type import under TYPE_CHECKING in python/xy/_figure.py lines
2220-2237 and python/xy/components.py lines 4172-4191. Keep the runtime
preflight import structure unchanged and use the forward-reference annotation to
avoid import cycles.